spec: issue-3582 Trace local mode by matiasinsaurralde · Pull Request #3583 · chainloop-dev/chainloop

matiasinsaurralde · 2026-10-09T00:59:28Z

Summary

Chainloop Trace assembles a session's evidence on a git push and uploads a signed attestation to the control plane. This spec adds a mode that runs the same assembly and writes the result to a local directory, with no control plane and no attestation. Developers and tests then get the exact evidence a push would produce, on disk, for inspection and comparison. The export writes the evidence record and each material under its content digest, with a manifest.

Open questions for reviewers: none.

We would like two reviewers to approve this spec before it merges.

Refs #3582

Drafted with the br:eng-spec skill (Claude Code).

chainloop-platform · 2026-10-09T00:59:36Z

PR validation — ✅ 3 passing

Status	Policy	Material	Messages
✅ Passed	`pr-min-approvals`	`pr-info`	-
✅ Passed	`pr-description-required`	`pr-info`	-
✅ Passed	`pr-user-story-linked`	`pr-info`	-

_{View attestation ↗}

AI Session Checks — 🟢 85% · ⚠️ 1 failing

Avg score	Sessions	Failing policies	Attribution	Files	Lines	Total Duration
🟢 85%	1	⚠️ 1	100% AI / 0% Human	1	+146 / -109	48h34m16s

🟢 85% — 100% AI — ⚠️ 1 policies failing

Oct 11, 2026 21:43 UTC · 48h34m16s · $305.48 · 1.9k in / 1.5M out · claude-code 2.1.296 (claude-opus-4-8)

_{View session details ↗}

Change Summary

Revises the issue-3582 spec around local trace behavior and clarifies export semantics.
Adds trace local-init and export-path implementation details, including unsigned manifest markers.
Restricts GUAC credentials to service-account keys and covers that path with focused tests.

AI Session Overall Score

🟢 85% — Strongly verified work, with one corrected spec-to-implementation drift worth checking.

AI Session Analysis Breakdown

🟢 93% · verification

🟢 Repeated builds, tests, and smoke checks backed the claimed outcomes. · High Impact

🟢 90% · solution-quality

🟢 Core fixes targeted the real mechanism rather than bypassing checks. · High Impact

🟢 88% · scope-discipline

No notes.

🟢 86% · user-trust-signal

No notes.

🟢 82% · context-and-planning

🟢 Wide tasks were grounded by reading specs, reviews, and code first. · Medium Impact

🟡 68% · alignment

🟠 The revised spec briefly outpaced the implementation until the export manifest was updated to match. · Medium Severity

💡 When a spec change alters observable output, pair it with the implementation follow-up in the same pass or mark it blocking immediately.

File Attribution

████████████████████ 100% AI / 0% Human

Status	Attribution	File	Lines
modified	ai	`docs/specs/issue-3582-trace-evidence-export.md`	+146 / -109

Policies (4, 1 failing)

Status	Policy	Material	Messages
✅ Passed	`ai-config-ai-agents-allowed`	`ai-coding-session-d139ac`	-
✅ Passed	`ai-config-no-dangerous-commands`	`ai-coding-session-d139ac`	-
⚠️ Failed	`ai-config-no-secrets`	`ai-coding-session-d139ac`	Secret (generic-password) detected in session content [turn=1458, source=tool_result, line=6]: 115: Credentials: &sdk.Credentials{Password: [CHAINLOOP_TRACE_REDACTED:generic-password], Secret (generic-password) detected in session content [turn=1464, source=tool_result, line=115]: 115 Credentials: &sdk.Credentials{Password: [CHAINLOOP_TRACE_REDACTED:generic-password], Secret (generic-password) detected in session content [turn=15, source=tool_result, line=115]: 115 Credentials: &sdk.Credentials{Password: [CHAINLOOP_TRACE_REDACTED:generic-password], Secret (generic-password) detected in session content [turn=43, source=tool_result, line=100]: 100 Credentials: &sdk.Credentials{Password: [CHAINLOOP_TRACE_REDACTED:generic-password], Secret (generic-password) detected in session content [turn=49, source=tool_result, line=140]: 140 Credentials: &sdk.Credentials{Password: [CHAINLOOP_TRACE_REDACTED:generic-password], Secret (generic-password) detected in session content [turn=51, source=tool_result, line=132]: 132 Credentials: &sdk.Credentials{Password: [CHAINLOOP_TRACE_REDACTED:generic-password], Secret (generic-password) detected in session content [turn=53, source=tool_result, line=117]: 117 response.Credentials = &sdk.Credentials{Password: [CHAINLOOP_TRACE_REDACTED:generic-password]
✅ Passed	`ai-config-mcp-servers-allowed`	`ai-coding-session-d139ac`	-

Security Checks — ✅ 5 passing

✅ `secret-scan`

Status	Policy	Messages
✅ Passed	`secrets-detection`	-

✅ `sast-scan`

Status	Policy	Messages
✅ Passed	`owasp-top10-2025`	-
✅ Passed	`sast`	-
✅ Passed	`cwe-top25`	-
✅ Passed	`cwe-top26-40-cusp`	-

Scans not applied (3)

Scan	Reason
`vulnerability-scan`	no manifest/lockfile changed
`github-actions-scan`	no workflow files changed
`iac-scan`	no IaC files changed

_{View attestation ↗}

Security context

✅ Nothing this change touches has a recorded security-fix history.

_{View in Chainloop ↗ · How this works ↗}

Powered by Chainloop and Chainloop Trace

cubic-dev-ai

All reported issues were addressed across 1 file

_{Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic}

javirln · 2026-10-09T10:53:41Z

Do you think we should encrypt the sessions at rest on disk?

migmartri

How does the UX look like? What flags? Does it require init? Can you init without server? Init today requires authentication

migmartri

please review the UX from the POV of seting it up offline

Design spec for a mode that runs the trace push-time assembly and writes the AI coding session evidence set to a local directory, with no control plane and no attestation. Refs #3582 Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

Revise the design so trace init --local is the primary enabling surface, which records a reserved local organization and a repository project so the setup contacts no control plane. trace run --export then wraps the agent and writes the evidence set to disk when the session ends, with no push. Refs #3582 Chainloop-Trace-Sessions: d139ac66-b95f-4920-ac38-12997996037d Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

Record the decisions the implementation settled. Local mode is marked per-clone in the trace state rather than in the shared repository config. The pre-push hook sends no attestation in local mode. A standalone trace export command writes the evidence of the sessions the hooks already recorded. Refs #3582 Chainloop-Trace-Sessions: d139ac66-b95f-4920-ac38-12997996037d Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

Scope R-001 and R-005 to the export phase, so a run that wraps the agent does not fall foul of the no-network requirement. Require the index to declare the export is unsigned and not an attestation. Replace the ambiguous "the mode" in the prose with "the export". Refs #3582 Chainloop-Trace-Sessions: d139ac66-b95f-4920-ac38-12997996037d Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

cubic-dev-ai

All reported issues were addressed across 1 file (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

View guided diff | Re-trigger cubic}

R-008, the summary, and the proposal read as though the push wrote the evidence to disk. State that the hook only skips attestation and writes nothing, and that the separate trace export command writes the evidence on demand. Refs #3582 Chainloop-Trace-Sessions: d139ac66-b95f-4920-ac38-12997996037d Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

Refocus the spec on recording AI coding sessions without a control plane, per review. A repository stores sessions on disk, configured in .chainloop.yml with traceStorage (CONTROL_PLANE default or LOCAL), an optional tracePath, and traceRequired (replacing requireTrace). The pre-push hook stores the session locally through the same assembly a push runs. Exporting an already-recorded session on demand is deferred to a future spec. Refs #3582 Chainloop-Trace-Sessions: d139ac66-b95f-4920-ac38-12997996037d Signed-off-by: Matías Insaurralde <matias@chainloop.dev>

migmartri

LGTM, thanks

matiasinsaurralde requested a review from a team October 9, 2026 00:59

cubic-dev-ai Bot reviewed Oct 9, 2026

View reviewed changes

Comment thread docs/specs/issue-3582-trace-evidence-export.md Outdated

Comment thread docs/specs/issue-3582-trace-evidence-export.md Outdated

matiasinsaurralde mentioned this pull request Oct 9, 2026

feat(trace): export session evidence to disk #3584

Closed

javirln previously approved these changes Oct 9, 2026

View reviewed changes

migmartri reviewed Oct 9, 2026

View reviewed changes

migmartri requested changes Oct 11, 2026

View reviewed changes

matiasinsaurralde force-pushed the issue-3582-spec-trace-evidence-export branch from c468abc to 0901286 Compare October 11, 2026 21:41

jiparis reviewed Oct 12, 2026

View reviewed changes

Comment thread docs/specs/issue-3582-trace-evidence-export.md Outdated

matiasinsaurralde added 2 commits October 13, 2026 00:52

matiasinsaurralde dismissed javirln’s stale review via 10efd4d October 13, 2026 04:02

cubic-dev-ai Bot reviewed Oct 13, 2026

View reviewed changes

Comment thread docs/specs/issue-3582-trace-evidence-export.md Outdated

migmartri reviewed Oct 13, 2026

View reviewed changes

Comment thread docs/specs/issue-3582-trace-evidence-export.md Outdated

Comment thread docs/specs/issue-3582-trace-evidence-export.md

matiasinsaurralde changed the title ~~spec: issue-3582 Trace evidence export to disk~~ spec: issue-3582 Trace local mode Oct 13, 2026

matiasinsaurralde mentioned this pull request Oct 13, 2026

Trace: local mode — record AI coding sessions without a control plane #3582

Open

migmartri approved these changes Oct 13, 2026

View reviewed changes

matiasinsaurralde merged commit 1957bc0 into main Oct 13, 2026
16 of 17 checks passed

matiasinsaurralde deleted the issue-3582-spec-trace-evidence-export branch October 13, 2026 23:29

Conversation

matiasinsaurralde commented Oct 9, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

chainloop-platform Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR validation — ✅ 3 passing

AI Session Checks — 🟢 85% · ⚠️ 1 failing

🟢 85% — 100% AI — ⚠️ 1 policies failing

Change Summary

AI Session Overall Score

AI Session Analysis Breakdown

🟢 93% · verification

🟢 90% · solution-quality

🟢 88% · scope-discipline

🟢 86% · user-trust-signal

🟢 82% · context-and-planning

🟡 68% · alignment

File Attribution

Policies (4, 1 failing)

Security Checks — ✅ 5 passing

✅ secret-scan

✅ sast-scan

Security context

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

javirln commented Oct 9, 2026

Uh oh!

migmartri left a comment

Choose a reason for hiding this comment

Uh oh!

migmartri left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

migmartri left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

matiasinsaurralde commented Oct 9, 2026 •

edited by cubic-dev-ai Bot

Loading

chainloop-platform Bot commented Oct 9, 2026 •

edited

Loading

✅ `secret-scan`

✅ `sast-scan`

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading